<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="lee ann fisk, lafisk@sandia.gov">
   <title> Zoltan Developer's Guide: Visualization of Geometric Partitions</title>

</head>
<body bgcolor="#FFFFFF">

<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Next</a>&nbsp; |&nbsp; <a href="dev_driver.html">Previous</a></i></b></div>


<h2>
<a NAME="Visualization"></a>Appendix: Visualization of Geometric Partitions 
</h2>

Graphical images of partitioned meshes can help you to understand the
geometric partitioning algorithms of Zoltan and to debug new or existing
algorithms.  The following sections describe methods for visualizing the
partitions computed by the <a href="dev_driver.html">test drivers</a>.

<h3>
<a NAME="Vis_2D"></a>2D problems with <I>gnuplot</I>
</h3>

To view the result of a 2D decomposition performed by the 
<a href="dev_driver.html">test driver</a>, 
use the "gnuplot output" option of the test driver input file, 
as described in <i><a href="zdrive.inp">zdrive.inp</a></i>.  The test driver
will write a file that can be loaded into <a href="https://www.gnuplot.info/">gnuplot</a>.
The result for the test mesh in directory <I>ch_hammond</I>, partitioned into four
regions with RCB, is show below. The first picture is obtained from the input file 
<i> zdrive.inp.gnuplot1</i> with <i>gnuplot output = 1</i>. The second
picture is obtained from the input file <i> zdrive.inp.gnuplot2</i>
with <i>gnuplot output = 2</i>.  Both pictures have been zoomed so
that the xrange is [-0.2,1.2] and the yrange is [-0.3,0.35].
<p>
<img src="hammondPoints.png" alt="[gnuplot 2D view]" border=2 height=488 width=654>
<p>
<p>
<img src="hammondMesh.png" alt="[gnuplot 2D view]" border=2 height=488 width=654>
<p>

<h3>
<a NAME="Vis_3D"></a>3D problems with <I>vtk_view</I>
</h3>
3D visualization requires downloading and compiling the 
<a href="https://www.vtk.org">Visualization Toolkit</a> (VTK) library (version
5.0 or later).  You can then use the Zoltan top level makefile to build
the <I>vtk_view</I> application found in the <I>util</I> directory of
Zoltan.  Build details can be found in the <I>Config.generic</I> file
in <I>Utilities/Config</I>.  Note that you will have to download and
build <a href = "https://www.cmake.org">CMake</a>, the makefile generator
used by <a href="https://www.vtk.org">VTK</a>, before you can build VTK.
<p>
<I>vtk_view</I> is a parallel MPI program.  It does not need to be
run with the same number of processes with which you ran <I>zdrive</I>.  You
can choose the number of processes based on the size of the input mesh you
will be visualizing, and the computational load of rendering it to an image
at interactive rates.
<p>
If you run <I>vtk_view</I> in the directory in which you ran
the test driver, the following will happen:
<UL>
<LI><I>vtk_view</I> will read <I><a href="zdrive.inp">zdrive.inp</a></I>, or another input parameter file
if you specify a different file on the command line.
<LI>It will read in the same input Chaco or Exodus II mesh that the test driver
read in.
<LI>It will read in the <i>file_name</i>.out.<i>p</i>.<i>n</i> files that the
test driver wrote listing the part assigned to every global ID.
<LI>It will open a window on your display, showing the input mesh.  For
Chaco files, the mesh vertices will be colored by the part into which
Zoltan placed them.  For Exodus II files, the mesh elements will be so colored.
A scalar bar in the window indicates the mapping from colors to part
numbers.  A caption describes the input file name, the decomposition
method, the Zoltan parameter settings, and so on.  You can use your mouse
to rotate the volume, pan and zoom in and out. 
</UL>
<p>
The example below shows how <I>vtk_view</I> displays the mesh in the test directory
<I>ch_brack2_3</I> after it has been partitioned with HSFC across 5 processes.
<p>
<img src="brack3d.png" alt="[vtk_view 3D view]" border=2 height=466 width=473>
<p>
If no test driver output files are found, <I>vtk_view</I> will 
display the mesh without part IDs.
<p>
There are a few additional options that can be added to the test driver
input file, that are specifically for <I>vtk_view</I>.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TD>zdrive count = &lt;number&gt;</TD>
     <TD>the number of <i>file_name</i>.out.<i>p</i>.<i>n</i> files, also the value of <i>p</i></TD>
<TR> <TD>image height = &lt;number&gt;</TD>
     <TD>number of pixels in height of image (default is <I>300</I>)</TD>
<TR> <TD>image width = &lt;number&gt;</TD>
     <TD>number of pixels in width of image (<I>300</I>)</TD>
<TR> <TD>omit caption = &lt;1 or 0&gt;</TD>
     <TD>do not print default caption in window if "1" (<I>0</I>) </TD>
<TR> <TD>omit scalar bar = &lt;1 or 0&gt;</TD>
     <TD>do not print scalar bar in window if "1" (<I>0</I>)</TD>
<TR> <TD>add caption = &lt;text of caption&gt;</TD>
     <TD>display indicated text in the window (<I>no caption</I>)</TD>
</TABLE>
<p>
The <I>zdrive count</I> option may be required if you have more than one
set of test driver output files in the directory.  Otherwise, <I>vtk_view</I>
will look for files of the form <i>file_name</i>.out.<i>p</i>.<i>n</i> for
any value <i>p</i>.  Note that since the window may be resized with the
mouse, you may not need <i>image height</i> and <i>image width</i>
unless you must have a very specific window size.  Also note that if you
ran the Fortan test driver <I>zfdrive</I>, you will need to rename the
output files from <i>file_name</i>.<B>f</B>out.<i>p</i>.<i>n</i> to
<i>file_name</i>.out.<i>p</i>.<i>n</i>.

<h3>
<a NAME="Vis_offscreen"></a>Off-screen rendering with <I>vtk_write</I>
</h3>
In some situations it is not possible or not convenient to open a window 
on a display.  In that case, you can compile <I>util/vtk_view.cpp</I> with the flag
<B>OUTPUT_TO_FILE</B> and it will create a program that renders the image
to a file instead of opening a window on a display.  (The Zoltan top level makefile
does exactly this when you use the <I>vtk_write</I> target.)
<p>
Note that while
<I>vtk_view</I> is built with OpenGL and <a href=https://www.vtk.org>VTK</a>, 
<I>vtk_write</I> must be built
with <a href = https://www.mesa3d.org>Mesa</a> GL and a version of the 
<a href=https://www.vtk.org>VTK</a> libraries that you have compiled with
special Mesa flags and with the Mesa header files.  This is because
OpenGL implementations are not
in general capable of off-screen rendering, and Mesa GL is.  The
<I>Config.generic</I> file in <I>Utilities/Config</I> describes in
detail how to build Mesa and then VTK for off-screen rendering.
<p>
<I>vtk_write</I> goes through the same steps that <I>vtk_view</I> does,
except at the end it writes one or more image files instead of opening
a window on your display.  The images begin with a camera focused on the
mesh, pointing in the direction of the negative Z-axis.  The positive
Y-axis is the "up" direction, and we use a right-handed coordinate
system.  (So the X-axis is pointing to the right.)  The camera can
revolve around the mesh in 1 degree increments.
<p>
The <I>zdrive count</I>, <I>image width</I>,  and <I>image height</I> 
options listed above also apply to <I>vtk_write</I>.  In addition, you
can use these options to govern the output images.

<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TD>output format = &lt;format name&gt;</TD>
     <TD>choices are tiff, png, jpeg, ps and bmp (default is <I>tiff</I>)</TD>
<TR> <TD>output name = &lt;file name&gt;</TD>
     <TD>base name of image file or files (<I>outfile</I>)</TD>
<TR> <TD>output frame start = &lt;number&gt;</TD>
     <TD>first frame, between 0 and 360 (<I>0</I>)</TD>
<TR> <TD>output frame stop = &lt;number&gt;</TD>
     <TD>last frame, between 0 and 360 (<I>0</I>)</TD>
<TR> <TD>output frame stride = &lt;number&gt;</TD>
     <TD>the difference in degrees from one frame to the next (<I>1</I>)</TD>
<TR> <TD>output view up = &lt;x y z&gt;</TD>
     <TD>the direction of "up" as camera points at mesh (<I>0 1 0</I>)</TD>
</TABLE>

<h3>
<a NAME="Vis_other"></a>Other file formats
</h3>
<I>vtk_view</I> was written to post-process <I>zdrive</I> runs, so it
only reads Chaco or Exodus II/Nemesis meshes.
If you are working with a different mesh-based file format, it
is still possible that you could use <I>vtk_view</I> or <I>vtk_write</I>
to view the parts assigned to your mesh by some application using the
Zoltan library.  <a href=https://www.vtk.org>VTK</a>
at this point in time has readers for many different file formats.  If VTK
has a reader for your format, then
modify the <I>read_mesh</I> function in <I>util/vtk_view.cpp</I> to use that
reader.  
<p>
You can then hard-code <I>vtk_view</I> to read your file, or you can
modify <I>read_cmd_file</I> in <I>driver/dr_input.c</I> to accept
a specification of your file type in addition to Chaco and Nemesis.  If
you do the latter you can create a <a href="zdrive.inp">zdrive-style
input file</a> in which to specify your file name and other visualization
parameters.
<p>
Finally, you need to create text files listing each global ID you supplied
to Zoltan, followed by the part ID assigned by Zoltan, with only
one global ID/part ID pair per line.  Name this
file or files using the conventions used by the 
<a href=dev_driver.html>test drivers</a>.

<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_test_script.html">Next:&nbsp;
Using the Test Script</a>&nbsp; |&nbsp; <a href="dev_driver.html">Previous:&nbsp;
Using the Test Drivers</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html
